Using the dslib Routines

Using the dslib Routines

To use the dslib library routines, include the header file dslib.h in your code and compile the code using the compiler option -lds. To open and close the device, your program must use the dslib routines dsopen() and dsclose(), rather than the open() and close() system calls. These routines set up data structures for the other library routines.

Note: This means that only specially compiled programs can use these devices; most standard programs will not be able to use them. The reason for this departure from IRIX is that dslib is actually a library of routines and macros that provide an interface to the device driver for the SCSI bus. By controlling the SCSI bus, you can control any device on that bus, providing the SCSI-bus device driver contains support for it. Such a SCSI-bus device driver is available on Silicon Graphics systems. However, using the ioctl() of the SCSI bus device driver directly can be complex. The routines of dslib provide access to ioctl() for the SCSI bus in a safe and relatively straightforward way.

For more on the dslib routines, see the online man pages dslib(3X) and ds(7M). The source for dslib is included in 4Dgifts.sw.giftsfull in 5.0 in the directory /usr/people/4Dgifts/examples/devices/devscsi.

Opening a SCSI Device

To open a device on the SCSI bus, a user-level program calls dsopen(), which calls the open() of the device driver for the SCSI bus and allocates data structures. If the open succeeds, the kernel allocates a SCSI subchannel for the device on the bus that you want to control. If this succeeds, a dsreq type structure is allocated, which in turn sets the values of some of its members and returns a pointer to this structure as its function value. This allocated and primed dsreq type structure is the medium of communication between your user program and the SCSI device.

Sending Commands to a SCSI Device

To send commands to the device on the SCSI bus, your program can modify the members of the dsreq type structure and call the dslib routine doscsireq(). This command uses an ioctl() call to the SCSI bus interface driver to set the members of the scsisubchan type structure for the device according to the information in the dsreq structure.

To simplify sending commands to a SCSI device, dslib provides routines and macros that set members of the dsreq type structure and call doscsireq(). For example, dslib provides the routine write0a() to give you an easy way to issue a simple group 0 "write" command. However, since few truly general SCSI commands exist, the dslib provides functions such as fillg0cmd() to give you a relatively painless way to send vendor-specific commands to a device on the SCSI bus. You can (and are expected) to extend these as needed, since the library source is included in the 4Dgifts subsystem.

Closing a SCSI Device

When your user-level program is done with the SCSI device, it must call dsclose() to close the device. This involves freeing the dsreq type structure and kernel data structures, among other things.